<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Docstrings &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Watching object attributes" href="attribute-watchers.html" />
    <link rel="prev" title="Tutorials" href="tutorials.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="docstrings">
<h1>Docstrings<a class="headerlink" href="#docstrings" title="Link to this heading">¶</a></h1>
<p>Each user-facing method on <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> or <code class="docutils literal notranslate"><span class="pre">Stage</span></code> should have a
docstring whose first line is suitable for use in the autocompletion
pop-up of the webapp’s editor.  Currently, Skulpt’s support for
introspection is incomplete, so we use a workaround for now.  The
docstring’s first line can start with a <code class="docutils literal notranslate"><span class="pre">&quot;(&quot;</span></code> character, in which
case everything up and including the first <code class="docutils literal notranslate"><span class="pre">&quot;)&quot;</span></code> character is used
as a <em>suffix</em> when presenting the completion to the user.  For
example, the docstring</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;(SOUND) Play SOUND; pause until it finishes playing&quot;</span>
</pre></div>
</div>
<p>for the method <code class="docutils literal notranslate"><span class="pre">play_sound_until_done</span></code> will result in the user being
shown something like</p>
<blockquote>
<div><p><em>play_sound_until_done(SOUND)</em> — Play SOUND; pause until it finishes playing</p>
</div></blockquote>
<p>If the docstring’s first line does not start with <code class="docutils literal notranslate"><span class="pre">&quot;(&quot;</span></code>, no suffix
is added to the attribute name when displaying it.  For example,
the docstring</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;The number of the costume SELF is currently wearing&quot;</span>
</pre></div>
</div>
<p>of the <code class="docutils literal notranslate"><span class="pre">costume_number</span></code> property will be shown along the lines of</p>
<blockquote>
<div><p><em>costume_number</em> — The number of the costume SELF is currently wearing</p>
</div></blockquote>
<p>in the webapp.</p>
<p>A unit test ensures that all methods and properties have docstrings,
apart from a set of hard-coded exceptions for non-user-facing
attributes.</p>
<section id="use-within-webapp">
<h2>Use within webapp<a class="headerlink" href="#use-within-webapp" title="Link to this heading">¶</a></h2>
<p>A function <code class="docutils literal notranslate"><span class="pre">pytch._user_facing_completions()</span></code> is intended for use by
the webapp.  It returns a dictionary mapping from parent name
(<code class="docutils literal notranslate"><span class="pre">pytch</span></code>, <code class="docutils literal notranslate"><span class="pre">Actor</span></code>, <code class="docutils literal notranslate"><span class="pre">Sprite</span></code>, <code class="docutils literal notranslate"><span class="pre">Stage</span></code>) to a list of simple
records giving the available user-facing attributes under that parent.
Each records is a tuple of strings:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">attribute</span><span class="o">-</span><span class="n">name</span><span class="p">,</span> <span class="n">suffix</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="n">doc</span><span class="p">)</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">suffix</span></code> and <code class="docutils literal notranslate"><span class="pre">doc</span></code> are parsed from the first docstring line
as outlined above.  The <code class="docutils literal notranslate"><span class="pre">kind</span></code> slot is currently ignored by the
webapp; it is the typename of the attribute’s value.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">VM</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="integration-with-client.html">Integration with client</a></li>
<li class="toctree-l3"><a class="reference internal" href="based-on-skulpt.html">Skulpt: Python / JavaScript bridge</a></li>
<li class="toctree-l3"><a class="reference internal" href="project.html">Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor.html">Actor: Sprite and Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor-registration.html">Actor-class registration</a></li>
<li class="toctree-l3"><a class="reference internal" href="threading-model.html">Threading model</a></li>
<li class="toctree-l3"><a class="reference internal" href="hat-blocks.html">Hat blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="syscalls.html">Syscalls</a></li>
<li class="toctree-l3"><a class="reference internal" href="skulpt-pytch-environment.html">Skulpt API / Pytch environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="ide-web-app.html">Web-app</a></li>
<li class="toctree-l3"><a class="reference internal" href="rendering.html">Rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="hit-detection.html">Collision and click detection</a></li>
<li class="toctree-l3"><a class="reference internal" href="clones.html">Clones</a></li>
<li class="toctree-l3"><a class="reference internal" href="sounds.html">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="attribute-watchers.html">Watching object attributes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>